Add `plot_waterfall` helper for dataframe-based waterfall charts by Copilot · Pull Request #93 · sdpython/teachpyx

Copilot · 2026-04-13T13:54:35Z

This issue asked for a function to generate a waterfall graph.
This PR adds a reusable plotting helper in teachpyx.tools with focused input validation and test coverage.

New plotting API (teachpyx.tools.pandas)
- Added plot_waterfall(data, value_column, label_column=None, total_label="total", ax=None, colors=(...))
- Computes cumulative starts/ends for each variation bar and appends a final total bar
- Supports plotting on an existing Matplotlib axis or creating one when ax is not provided
- Returns (ax, plot_df) so computed geometry can be inspected/reused
Input validation
- Raises ValueError when:
  - value_column is missing
  - label_column is provided but missing
  - value_column cannot be converted to numeric
  - colors does not contain exactly 3 entries (positive / negative / total)
Unit tests (_unittests/ut_tools/test_pandas.py)
- Added focused tests for nominal waterfall computation (labels, start/end progression, total)
- Added tests for all validation/error branches

Example usage:

import pandas as pd
from teachpyx.tools.pandas import plot_waterfall

df = pd.DataFrame({"name": ["A", "B", "C"], "delta": [10, -3, 5]})
ax, plot_df = plot_waterfall(df, "delta", "name", total_label="TOTAL")

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/e6e8e7c7-c0a1-47b3-9763-5ebb04affcb9 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

xadupre · 2026-04-13T14:29:13Z

teachpyx/tools/pandas.py

+    if len(colors) != 3:
+        raise ValueError(f"colors must contain 3 values, not {len(colors)}.")
+
+    try:


@copilot enleve moi ça (try catch)

Fait dans le commit 90a5382 : le try/except autour de pandas.to_numeric a été supprimé dans plot_waterfall.

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/51a3850a-5547-4962-a7d6-829066c3c6ff Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

xadupre · 2026-04-13T14:32:51Z

@copilot ajoute un vrai exemple dans la documentation

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/242bb04a-1d52-4f54-a254-e242a90f9ed5 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Copilot · 2026-04-13T14:41:52Z

@copilot ajoute un vrai exemple dans la documentation

C’est fait dans c22383e : j’ai ajouté un vrai exemple rendu dans la doc (_doc/api/tools/pandas.rst) avec un bloc .. plot:: qui montre l’usage complet de plot_waterfall et le graphique produit.

Copilot

Pull request overview

Adds a new dataframe-based helper for producing waterfall charts in teachpyx.tools.pandas, along with documentation and unit tests to validate both computation and error handling.

Changes:

Added plot_waterfall to compute waterfall bar geometry (start/end) and render a Matplotlib bar chart, returning both (ax, plot_df).
Added unit tests covering nominal geometry/labels and all documented validation/error branches.
Updated Sphinx API docs with a runnable .. plot:: example for the new helper.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
`teachpyx/tools/pandas.py`	Introduces `plot_waterfall` with input validation, geometry computation, and Matplotlib plotting.
`_unittests/ut_tools/test_pandas.py`	Adds tests for waterfall computation and validation branches.
`_doc/api/tools/pandas.rst`	Documents `plot_waterfall` via a Sphinx plot example and includes it in module API output.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-13T14:56:31Z

_unittests/ut_tools/test_pandas.py

@@ -14,6 +16,39 @@ def test_read_csv_cached(self):
        self.assertEqual(df.shape, df2.shape)
        self.assertEqual(list(df.columns), list(df2.columns))

+    def test_plot_waterfall(self):
+        df = pandas.DataFrame(
+            {
+                "name": ["A", "B", "C"],
+                "delta": [10, -3, 5],
+            }
+        )
+        ax, plot_df = plot_waterfall(df, "delta", "name", total_label="TOTAL")
+        self.assertIsInstance(ax, Axes)
+        self.assertEqual(list(plot_df["label"]), ["A", "B", "C", "TOTAL"])
+        self.assertEqual(list(plot_df["start"]), [0.0, 10.0, 7.0, 0.0])
+        self.assertEqual(list(plot_df["end"]), [10.0, 7.0, 12.0, 12.0])


plot_waterfall creates a new Matplotlib figure when ax is None, and this unit test will exercise that path. In headless CI environments, importing/using matplotlib.pyplot can fail or pick an interactive backend unless a non-interactive backend (e.g., Agg) is forced by the test runner/environment. Consider explicitly forcing a non-interactive backend for this test suite (or in this test) and closing the created figure to avoid accumulating open figures across tests.

Copilot · 2026-04-13T14:56:32Z

teachpyx/tools/pandas.py

+    :param colors: positive, negative, total colors
+    :return: axis, computed dataframe used to draw the chart
+
+    .. versionadded:: 0.6.1


The docstring marks this helper as .. versionadded:: 0.6.1, but the project version in pyproject.toml is currently 0.6.0. Please align the versionadded tag with the release version that will actually contain this function (either bump the package version as part of this change, or adjust the tag) to avoid misleading API docs.

Suggested change

.. versionadded:: 0.6.1

.. versionadded:: 0.6.0

Initial plan

047dbfd

Copilot AI assigned Copilot and xadupre Apr 13, 2026

Copilot started work on behalf of xadupre April 13, 2026 13:54 View session

Copilot AI linked an issue Apr 13, 2026 that may be closed by this pull request

implémenter une fonction qui fait un waterfall (graphe) #92

Open

Copilot AI and others added 5 commits April 13, 2026 14:00

Add waterfall chart helper and focused tests

0d5d398

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/e6e8e7c7-c0a1-47b3-9763-5ebb04affcb9 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Add extra validation tests for waterfall helper

eb76c60

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/e6e8e7c7-c0a1-47b3-9763-5ebb04affcb9 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Refine waterfall validation and test assertions

f34b7a6

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/e6e8e7c7-c0a1-47b3-9763-5ebb04affcb9 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Polish waterfall implementation per review

f79dc95

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/e6e8e7c7-c0a1-47b3-9763-5ebb04affcb9 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Add non-numeric input test for waterfall helper

bbdac40

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/e6e8e7c7-c0a1-47b3-9763-5ebb04affcb9 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Implement function for waterfall graph~~ Add plot_waterfall helper for dataframe-based waterfall charts Apr 13, 2026

Copilot finished work on behalf of xadupre April 13, 2026 14:06

Copilot AI requested a review from xadupre April 13, 2026 14:06

xadupre reviewed Apr 13, 2026

View reviewed changes

Copilot started work on behalf of xadupre April 13, 2026 14:29 View session

Remove try/except from waterfall numeric conversion

90a5382

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/51a3850a-5547-4962-a7d6-829066c3c6ff Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Copilot finished work on behalf of xadupre April 13, 2026 14:35

Copilot AI requested a review from xadupre April 13, 2026 14:35

Copilot started work on behalf of xadupre April 13, 2026 14:35 View session

Copilot AI and others added 2 commits April 13, 2026 14:40

Add concrete documentation example for plot_waterfall

ac74fce

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/242bb04a-1d52-4f54-a254-e242a90f9ed5 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Polish waterfall doc example wording

c22383e

Agent-Logs-Url: https://github.com/sdpython/teachpyx/sessions/242bb04a-1d52-4f54-a254-e242a90f9ed5 Co-authored-by: xadupre <22452781+xadupre@users.noreply.github.com>

Copilot finished work on behalf of xadupre April 13, 2026 14:42

xadupre requested a review from Copilot April 13, 2026 14:52

Copilot started reviewing on behalf of xadupre April 13, 2026 14:53 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `plot_waterfall` helper for dataframe-based waterfall charts#93

Add `plot_waterfall` helper for dataframe-based waterfall charts#93
Copilot wants to merge 9 commits intomainfrom
copilot/implement-waterfall-graph-function

Copilot AI commented Apr 13, 2026 •

edited

Loading

Uh oh!

xadupre Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

xadupre commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xadupre Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

xadupre commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 13, 2026 •

edited

Loading